<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<link rel="shortcut icon" type="image/x-icon" href="favicon.ico"/>
<title>DynamoRIO API: Function Wrapping and Replacing</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { searchBox.OnSelectItem(0); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">DynamoRIO API
   </div>
  </td>
   <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.1.1 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group__drwrap.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark">&#160;</span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark">&#160;</span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark">&#160;</span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark">&#160;</span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark">&#160;</span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark">&#160;</span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark">&#160;</span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark">&#160;</span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark">&#160;</span>Macros</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark">&#160;</span>Groups</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(10)"><span class="SelectionMark">&#160;</span>Pages</a></div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="summary">
<a href="#define-members">Macros</a> &#124;
<a href="#enum-members">Enumerations</a> &#124;
<a href="#func-members">Functions</a>  </div>
  <div class="headertitle">
<div class="title">Function Wrapping and Replacing</div>  </div>
</div><!--header-->
<div class="contents">
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="define-members"></a>
Macros</h2></td></tr>
<tr class="memitem:ga925e96b9b70bcf935279bfd79dbe6c7f"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga925e96b9b70bcf935279bfd79dbe6c7f">DRMGR_PRIORITY_NAME_DRWRAP</a>&#160;&#160;&#160;&quot;drwrap&quot;</td></tr>
<tr class="memitem:ga0f9e93e3ba51cc96470fd261eaa55273"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga0f9e93e3ba51cc96470fd261eaa55273">DRWRAP_REPLACE_NATIVE_DATA_SLOT</a>&#160;&#160;&#160;<a class="el" href="dr__ir__utils_8h.html#a89a6b714ff24d91d78589877047a29b9ae4cd78beccb2525acc61f2536ba1ea71">SPILL_SLOT_2</a></td></tr>
<tr class="memitem:gad88566adce8386b5d2e6c6de83e21e8b"><td class="memItemLeft" align="right" valign="top">#define&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#gad88566adce8386b5d2e6c6de83e21e8b">DRWRAP_REPLACE_NATIVE_SP_SLOT</a>&#160;&#160;&#160;<a class="el" href="dr__ir__utils_8h.html#a89a6b714ff24d91d78589877047a29b9a446ae7a7df24d2c3abae567a17289566">SPILL_SLOT_3</a></td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="enum-members"></a>
Enumerations</h2></td></tr>
<tr class="memitem:gab48899087cc647f0f791ed0c459adc53"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom">{ <br/>
&#160;&#160;<a class="el" href="group__drwrap.html#ggab48899087cc647f0f791ed0c459adc53a556c6bce97b9c415e089261848536c14">DRMGR_PRIORITY_APP2APP_DRWRAP</a> =  -500, 
<br/>
&#160;&#160;<a class="el" href="group__drwrap.html#ggab48899087cc647f0f791ed0c459adc53ada17e11e67b93129fede7890e032bbbd">DRMGR_PRIORITY_INSERT_DRWRAP</a> =  500, 
<br/>
&#160;&#160;<a class="el" href="group__drwrap.html#ggab48899087cc647f0f791ed0c459adc53af45be46f89c86ce07739c8243fde7f5d">DRMGR_PRIORITY_FAULT_DRWRAP</a> =  500
<br/>
 }</td></tr>
<tr class="memitem:ga16cc419209fcb0024d010599bb82aa76"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga16cc419209fcb0024d010599bb82aa76">drwrap_wrap_flags_t</a> { <a class="el" href="group__drwrap.html#gga16cc419209fcb0024d010599bb82aa76aaee35c5aabcb42793293b905c448e1c6">DRWRAP_UNWIND_ON_EXCEPTION</a> =  0x01
 }</td></tr>
<tr class="memitem:gab82c71baab4fe0c5f9962383818b9c92"><td class="memItemLeft" align="right" valign="top">enum &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#gab82c71baab4fe0c5f9962383818b9c92">drwrap_global_flags_t</a> { <br/>
&#160;&#160;<a class="el" href="group__drwrap.html#ggab82c71baab4fe0c5f9962383818b9c92af1b2f3860316577a15e3430942febc8a">DRWRAP_SAFE_READ_RETADDR</a> =  0x01, 
<br/>
&#160;&#160;<a class="el" href="group__drwrap.html#ggab82c71baab4fe0c5f9962383818b9c92ab7a628a50b1344c943a703a72e5cfce9">DRWRAP_SAFE_READ_ARGS</a> =  0x02, 
<br/>
&#160;&#160;<a class="el" href="group__drwrap.html#ggab82c71baab4fe0c5f9962383818b9c92aeb299993e17993cb86912f93391f6b86">DRWRAP_NO_FRILLS</a> =  0x04, 
<br/>
&#160;&#160;<a class="el" href="group__drwrap.html#ggab82c71baab4fe0c5f9962383818b9c92add150e3e7ba4ee203a045b936f872b4b">DRWRAP_FAST_CLEANCALLS</a> =  0x08
<br/>
 }</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr class="memitem:ga23837833101ebc340ac7de6e8340bb4a"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga23837833101ebc340ac7de6e8340bb4a">drwrap_init</a> (void)</td></tr>
<tr class="memitem:ga0e58babc53301c4ade4027dc1e09a088"><td class="memItemLeft" align="right" valign="top">DR_EXPORT void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga0e58babc53301c4ade4027dc1e09a088">drwrap_exit</a> (void)</td></tr>
<tr class="memitem:ga488a6566cd760a3919bdd2f49a6d672f"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga488a6566cd760a3919bdd2f49a6d672f">drwrap_replace</a> (app_pc original, app_pc replacement, bool override)</td></tr>
<tr class="memitem:ga0ae2e383b0005a46848c7d0497be563a"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga0ae2e383b0005a46848c7d0497be563a">drwrap_replace_native</a> (app_pc original, app_pc replacement, bool at_entry, uint stack_adjust, void *user_data, bool override)</td></tr>
<tr class="memitem:ga3f23eb9d8bd537881dcea9ecb19b5a4f"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga3f23eb9d8bd537881dcea9ecb19b5a4f">drwrap_is_replaced</a> (app_pc func)</td></tr>
<tr class="memitem:ga87ab96ab2d3c5cc33480693266b33249"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga87ab96ab2d3c5cc33480693266b33249">drwrap_is_replaced_native</a> (app_pc func)</td></tr>
<tr class="memitem:gadadab62f67c3e8198762776012a66fce"><td class="memItemLeft" align="right" valign="top">DR_EXPORT void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#gadadab62f67c3e8198762776012a66fce">drwrap_replace_native_fini</a> (void *drcontext)</td></tr>
<tr class="memitem:ga4c004987daae07af15f2146c2d7d4b09"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga4c004987daae07af15f2146c2d7d4b09">drwrap_wrap</a> (app_pc func, void(*pre_func_cb)(void *wrapcxt, OUT void **user_data), void(*post_func_cb)(void *wrapcxt, void *user_data))</td></tr>
<tr class="memitem:gaff6f66f7ec021cea150eb753f5db2b75"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#gaff6f66f7ec021cea150eb753f5db2b75">drwrap_wrap_ex</a> (app_pc func, void(*pre_func_cb)(void *wrapcxt, INOUT void **user_data), void(*post_func_cb)(void *wrapcxt, void *user_data), void *user_data, <a class="el" href="group__drwrap.html#ga16cc419209fcb0024d010599bb82aa76">drwrap_wrap_flags_t</a> flags)</td></tr>
<tr class="memitem:ga27894370f3da794ff3f31cb8d7ec079b"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga27894370f3da794ff3f31cb8d7ec079b">drwrap_unwrap</a> (app_pc func, void(*pre_func_cb)(void *wrapcxt, OUT void **user_data), void(*post_func_cb)(void *wrapcxt, void *user_data))</td></tr>
<tr class="memitem:ga92584c3e1980ac0c467de7d14d2bc2a2"><td class="memItemLeft" align="right" valign="top">DR_EXPORT app_pc&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga92584c3e1980ac0c467de7d14d2bc2a2">drwrap_get_drcontext</a> (void *wrapcxt)</td></tr>
<tr class="memitem:ga106eb283e97c560a0118b8da211b7f1a"><td class="memItemLeft" align="right" valign="top">DR_EXPORT app_pc&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga106eb283e97c560a0118b8da211b7f1a">drwrap_get_func</a> (void *wrapcxt)</td></tr>
<tr class="memitem:ga9a33b1049986dd8975e94827f5c0e759"><td class="memItemLeft" align="right" valign="top">DR_EXPORT <a class="el" href="dr__defines_8h.html#a5d50a4225e834d67f66438669608e435">dr_mcontext_t</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga9a33b1049986dd8975e94827f5c0e759">drwrap_get_mcontext</a> (void *wrapcxt)</td></tr>
<tr class="memitem:gac3a79cf043d8c21dc190721d9fb105de"><td class="memItemLeft" align="right" valign="top">DR_EXPORT <a class="el" href="dr__defines_8h.html#a5d50a4225e834d67f66438669608e435">dr_mcontext_t</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#gac3a79cf043d8c21dc190721d9fb105de">drwrap_get_mcontext_ex</a> (void *wrapcxt, <a class="el" href="dr__defines_8h.html#af0434595b47158e7512c2bf5f0e43ae4">dr_mcontext_flags_t</a> flags)</td></tr>
<tr class="memitem:gae4a50709cf98fca89860c09543176fa6"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#gae4a50709cf98fca89860c09543176fa6">drwrap_set_mcontext</a> (void *wrapcxt)</td></tr>
<tr class="memitem:ga2da9c1f9ef091b6856a98c6ce5e2a3f5"><td class="memItemLeft" align="right" valign="top">DR_EXPORT app_pc&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga2da9c1f9ef091b6856a98c6ce5e2a3f5">drwrap_get_retaddr</a> (void *wrapcxt)</td></tr>
<tr class="memitem:ga3d0864daf1ec37a91640a739f8928b83"><td class="memItemLeft" align="right" valign="top">DR_EXPORT void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga3d0864daf1ec37a91640a739f8928b83">drwrap_get_arg</a> (void *wrapcxt, int arg)</td></tr>
<tr class="memitem:ga17937b1d8ff7e391814e4e6e6df5c807"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga17937b1d8ff7e391814e4e6e6df5c807">drwrap_set_arg</a> (void *wrapcxt, int arg, void *val)</td></tr>
<tr class="memitem:gae993f55e025cf80ae67ed398b35a1b61"><td class="memItemLeft" align="right" valign="top">DR_EXPORT void *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#gae993f55e025cf80ae67ed398b35a1b61">drwrap_get_retval</a> (void *wrapcxt)</td></tr>
<tr class="memitem:gafd31e6725143df904e766dbfa508db05"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#gafd31e6725143df904e766dbfa508db05">drwrap_set_retval</a> (void *wrapcxt, void *val)</td></tr>
<tr class="memitem:gae539b1092ba0c1a3e86172964a671805"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#gae539b1092ba0c1a3e86172964a671805">drwrap_skip_call</a> (void *wrapcxt, void *retval, size_t stdcall_args_size)</td></tr>
<tr class="memitem:ga0f84bd239ed2f9f3550d66b75fb9b392"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga0f84bd239ed2f9f3550d66b75fb9b392">drwrap_register_post_call_notify</a> (void(*cb)(app_pc pc))</td></tr>
<tr class="memitem:ga1b4b6da75fceb5977ff1f82bf3ffd8c9"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga1b4b6da75fceb5977ff1f82bf3ffd8c9">drwrap_unregister_post_call_notify</a> (void(*cb)(app_pc pc))</td></tr>
<tr class="memitem:ga61b97c33203c704dd8ff1b9d31b3d2a9"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga61b97c33203c704dd8ff1b9d31b3d2a9">drwrap_mark_as_post_call</a> (app_pc pc)</td></tr>
<tr class="memitem:gae2cc2affaf879182ba4d92299704c65f"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#gae2cc2affaf879182ba4d92299704c65f">drwrap_set_global_flags</a> (<a class="el" href="group__drwrap.html#gab82c71baab4fe0c5f9962383818b9c92">drwrap_global_flags_t</a> flags)</td></tr>
<tr class="memitem:ga01e56e9bac8f584fe25e806a24769d50"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga01e56e9bac8f584fe25e806a24769d50">drwrap_is_wrapped</a> (app_pc func, void(*pre_func_cb)(void *wrapcxt, OUT void **user_data), void(*post_func_cb)(void *wrapcxt, void *user_data))</td></tr>
<tr class="memitem:ga16fc2d260f5ebead724d5eb98bf13ac2"><td class="memItemLeft" align="right" valign="top">DR_EXPORT bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__drwrap.html#ga16fc2d260f5ebead724d5eb98bf13ac2">drwrap_is_post_wrap</a> (app_pc pc)</td></tr>
</table>
<hr/><a name="details" id="details"></a><h2>Detailed Description</h2>
<hr/><h2>Macro Definition Documentation</h2>
<a class="anchor" id="ga925e96b9b70bcf935279bfd79dbe6c7f"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">#define DRMGR_PRIORITY_NAME_DRWRAP&#160;&#160;&#160;&quot;drwrap&quot;</td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Name of drmgr instrumentation pass priorities for app2app, insert, and exception on Windows. </p>

</div>
</div>
<a class="anchor" id="ga0f9e93e3ba51cc96470fd261eaa55273"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">#define DRWRAP_REPLACE_NATIVE_DATA_SLOT&#160;&#160;&#160;<a class="el" href="dr__ir__utils_8h.html#a89a6b714ff24d91d78589877047a29b9ae4cd78beccb2525acc61f2536ba1ea71">SPILL_SLOT_2</a></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Spill slot used to store user_data parameter for <a class="el" href="group__drwrap.html#ga0ae2e383b0005a46848c7d0497be563a">drwrap_replace_native()</a> </p>

</div>
</div>
<a class="anchor" id="gad88566adce8386b5d2e6c6de83e21e8b"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">#define DRWRAP_REPLACE_NATIVE_SP_SLOT&#160;&#160;&#160;<a class="el" href="dr__ir__utils_8h.html#a89a6b714ff24d91d78589877047a29b9a446ae7a7df24d2c3abae567a17289566">SPILL_SLOT_3</a></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Spill slot used to store application stack address for <a class="el" href="group__drwrap.html#ga0ae2e383b0005a46848c7d0497be563a">drwrap_replace_native()</a> </p>

</div>
</div>
<hr/><h2>Enumeration Type Documentation</h2>
<a class="anchor" id="gab48899087cc647f0f791ed0c459adc53"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">anonymous enum</td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Priorities of drmgr instrumentation passes used by drwrap. Users of drwrap can use the name DRMGR_PRIORITY_NAME_DRWRAP in the <a class="el" href="struct__drmgr__priority__t.html#ac73be551eedc5f37043fb752b30eec32">drmgr_priority_t.before</a> field or can use these numeric priorities in the <a class="el" href="struct__drmgr__priority__t.html#a2e46fa4cbefc2dc32f3bc73e8bd82d3e">drmgr_priority_t.priority</a> field to ensure proper instrumentation pass ordering. </p>
<dl><dt><b>Enumerator: </b></dt><dd><table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><em><a class="anchor" id="ggab48899087cc647f0f791ed0c459adc53a556c6bce97b9c415e089261848536c14"></a>DRMGR_PRIORITY_APP2APP_DRWRAP</em>&nbsp;</td><td>
<p>Priority of <a class="el" href="group__drwrap.html#ga488a6566cd760a3919bdd2f49a6d672f">drwrap_replace()</a> </p>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="ggab48899087cc647f0f791ed0c459adc53ada17e11e67b93129fede7890e032bbbd"></a>DRMGR_PRIORITY_INSERT_DRWRAP</em>&nbsp;</td><td>
<p>Priority of <a class="el" href="group__drwrap.html#ga4c004987daae07af15f2146c2d7d4b09">drwrap_wrap()</a> </p>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="ggab48899087cc647f0f791ed0c459adc53af45be46f89c86ce07739c8243fde7f5d"></a>DRMGR_PRIORITY_FAULT_DRWRAP</em>&nbsp;</td><td>
<p>Priority of fault handling event </p>
</td></tr>
</table>
</dd>
</dl>

</div>
</div>
<a class="anchor" id="gab82c71baab4fe0c5f9962383818b9c92"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">enum <a class="el" href="group__drwrap.html#gab82c71baab4fe0c5f9962383818b9c92">drwrap_global_flags_t</a></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Values for the flags parameter to <a class="el" href="group__drwrap.html#gae2cc2affaf879182ba4d92299704c65f">drwrap_set_global_flags()</a> </p>
<dl><dt><b>Enumerator: </b></dt><dd><table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><em><a class="anchor" id="ggab82c71baab4fe0c5f9962383818b9c92af1b2f3860316577a15e3430942febc8a"></a>DRWRAP_SAFE_READ_RETADDR</em>&nbsp;</td><td>
<p>By default the return address is read directly. A more conservative and safe approach would use a safe read to avoid crashing when the stack is unsafe to access. This flag will cause the return address to be read safely. If any call to <a class="el" href="group__drwrap.html#gae2cc2affaf879182ba4d92299704c65f">drwrap_set_global_flags()</a> sets this flag, no later call can remove it. </p>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="ggab82c71baab4fe0c5f9962383818b9c92ab7a628a50b1344c943a703a72e5cfce9"></a>DRWRAP_SAFE_READ_ARGS</em>&nbsp;</td><td>
<p>By default function arguments stored in memory are read and written directly. A more conservative and safe approach would use a safe read or write to avoid crashing when the stack is unsafe to access. This flag will cause all arguments in memory to be read and written safely. If any call to <a class="el" href="group__drwrap.html#gae2cc2affaf879182ba4d92299704c65f">drwrap_set_global_flags()</a> sets this flag, no later call can remove it. </p>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="ggab82c71baab4fe0c5f9962383818b9c92aeb299993e17993cb86912f93391f6b86"></a>DRWRAP_NO_FRILLS</em>&nbsp;</td><td>
<p>If this flag is set, then a leaner wrapping mechanism is used with lower overhead. However, several features are not supported with this flag:</p>
<ul>
<li>Only one wrap request per address is allowed. A second request will fail, even if an earlier request was unwrapped, unless the same pre and post callback functions are used.</li>
<li>Wrapping should occur prior to any execution (e.g., at startup or module load time). A new wrap request that occurs between the pre and post wrap points may have its post callback called even though its pre callback was never called.</li>
<li>Unwrapping should only happen on module unload. It is not supported between a pre and post callback. Only set this flag if you are certain that all uses of wrapping in your client and all libraries it uses can abide the above restrictions. Once set, this flag cannot be unset. </li>
</ul>
</td></tr>
<tr><td valign="top"><em><a class="anchor" id="ggab82c71baab4fe0c5f9962383818b9c92add150e3e7ba4ee203a045b936f872b4b"></a>DRWRAP_FAST_CLEANCALLS</em>&nbsp;</td><td>
<p>If this flag is set, then a leaner clean call is used to invoke wrap pre callbacks. This clean call assumes that all wrap requests are for function entrance points and that standard ABI calling conventions are used for those functions. This means that caller-saved registers may not be saved and thus will have invalid values in <a class="el" href="group__drwrap.html#ga9a33b1049986dd8975e94827f5c0e759">drwrap_get_mcontext()</a>. When using this setting and skipping a function via <a class="el" href="group__drwrap.html#gae539b1092ba0c1a3e86172964a671805">drwrap_skip_call()</a> (or calling <a class="el" href="dr__ir__utils_8h.html#a9f612cf9d0ca2025b23d30b6f5bb0231">dr_redirect_execution()</a> directly), setting xmm registers (in particular those used as return values) will work correctly (of course, be sure to retrieve the existing xmm values via <a class="el" href="group__drwrap.html#ga9a33b1049986dd8975e94827f5c0e759">drwrap_get_mcontext()</a> or drwrap_get_mcontext_ex(DR_MC_ALL) first).</p>
<p>Only set this flag if you are certain that all uses of wrapping in your client and all libraries it uses can abide the above restrictions. Once set, this flag cannot be unset. </p>
</td></tr>
</table>
</dd>
</dl>

</div>
</div>
<a class="anchor" id="ga16cc419209fcb0024d010599bb82aa76"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">enum <a class="el" href="group__drwrap.html#ga16cc419209fcb0024d010599bb82aa76">drwrap_wrap_flags_t</a></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Values for the flags parameter to <a class="el" href="group__drwrap.html#gaff6f66f7ec021cea150eb753f5db2b75">drwrap_wrap_ex()</a> </p>
<dl><dt><b>Enumerator: </b></dt><dd><table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"><em><a class="anchor" id="gga16cc419209fcb0024d010599bb82aa76aaee35c5aabcb42793293b905c448e1c6"></a>DRWRAP_UNWIND_ON_EXCEPTION</em>&nbsp;</td><td>
<p>If this flag is set, then when a Windows exception occurs, all post-call callbacks for all live wrapped functions on the wrap stack for which <code>unwind_on_exception</code> is true are called. If this flag is not set (the default), each post-call callback will still be called if drwrap's heuristics later detect that that particular callback has been bypassed, but those heuristics are not guaranteed. </p>
</td></tr>
</table>
</dd>
</dl>

</div>
</div>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga0e58babc53301c4ade4027dc1e09a088"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT void drwrap_exit </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Cleans up the drwrap extension. </p>

</div>
</div>
<a class="anchor" id="ga3d0864daf1ec37a91640a739f8928b83"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT void* drwrap_get_arg </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>arg</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the value of the <code>arg-th</code> argument (0-based) to the wrapped function represented by <code>wrapcxt</code>. Assumes the regular C calling convention (i.e., no fastcall). May only be called from a <code>drwrap_wrap</code> pre-function callback. To access argument values in a post-function callback, store them in the <code>user_data</code> parameter passed between the pre and post functions.</p>
<p>This routine may de-reference application memory directly, so the caller should wrap in DR_TRY_EXCEPT if crashes must be avoided. </p>

</div>
</div>
<a class="anchor" id="ga92584c3e1980ac0c467de7d14d2bc2a2"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT app_pc drwrap_get_drcontext </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the DynamoRIO context. This routine can be faster than <a class="el" href="dr__tools_8h.html#a13217cc252506b06184c7c72adedf26c">dr_get_current_drcontext()</a> but should return the same result. </p>

</div>
</div>
<a class="anchor" id="ga106eb283e97c560a0118b8da211b7f1a"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT app_pc drwrap_get_func </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the address of the wrapped function represented by <code>wrapcxt</code>. </p>

</div>
</div>
<a class="anchor" id="ga9a33b1049986dd8975e94827f5c0e759"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT <a class="el" href="dr__defines_8h.html#a5d50a4225e834d67f66438669608e435">dr_mcontext_t</a>* drwrap_get_mcontext </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the machine context of the wrapped function represented by <code>wrapcxt</code> corresponding to the application state at the time of the pre-function or post-function wrap callback. In order for any changes to the returned context to take effect, <a class="el" href="group__drwrap.html#gae4a50709cf98fca89860c09543176fa6">drwrap_set_mcontext()</a> must be called.</p>
<dl class="section note"><dt>Note:</dt><dd>if the <a class="el" href="group__drwrap.html#ggab82c71baab4fe0c5f9962383818b9c92add150e3e7ba4ee203a045b936f872b4b">DRWRAP_FAST_CLEANCALLS</a> flag is set, caller-saved register values in the fields controlled by <a class="el" href="dr__defines_8h.html#af0434595b47158e7512c2bf5f0e43ae4af3780bef723b8bf1a34eb75125f7f122">DR_MC_MULTIMEDIA</a> will not contain valid values. </dd></dl>

</div>
</div>
<a class="anchor" id="gac3a79cf043d8c21dc190721d9fb105de"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT <a class="el" href="dr__defines_8h.html#a5d50a4225e834d67f66438669608e435">dr_mcontext_t</a>* drwrap_get_mcontext_ex </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="dr__defines_8h.html#af0434595b47158e7512c2bf5f0e43ae4">dr_mcontext_flags_t</a>&#160;</td>
          <td class="paramname"><em>flags</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Identical to <a class="el" href="group__drwrap.html#ga9a33b1049986dd8975e94827f5c0e759">drwrap_get_mcontext()</a> but only fills in the state indicated by <code>flags</code>. </p>

</div>
</div>
<a class="anchor" id="ga2da9c1f9ef091b6856a98c6ce5e2a3f5"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT app_pc drwrap_get_retaddr </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the return address of the wrapped function represented by <code>wrapcxt</code>.</p>
<p>This routine may de-reference application memory directly, so the caller should wrap in DR_TRY_EXCEPT if crashes must be avoided. </p>

</div>
</div>
<a class="anchor" id="gae993f55e025cf80ae67ed398b35a1b61"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT void* drwrap_get_retval </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Returns the return value of the wrapped function represented by <code>wrapcxt</code>. Assumes a pointer-sized return value. May only be called from a <code>drwrap_wrap</code> post-function callback. </p>

</div>
</div>
<a class="anchor" id="ga23837833101ebc340ac7de6e8340bb4a"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_init </td>
          <td>(</td>
          <td class="paramtype">void&#160;</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Initializes the drwrap extension. Must be called prior to any of the other routines. Can be called multiple times (by separate components, normally) but each call must be paired with a corresponding call to <a class="el" href="group__drwrap.html#ga0e58babc53301c4ade4027dc1e09a088">drwrap_exit()</a>.</p>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="ga16fc2d260f5ebead724d5eb98bf13ac2"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_is_post_wrap </td>
          <td>(</td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>pc</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<dl class="section return"><dt>Returns:</dt><dd>whether <code>pc</code> is currently considered a post-wrap point, for any wrap request. </dd></dl>

</div>
</div>
<a class="anchor" id="ga3f23eb9d8bd537881dcea9ecb19b5a4f"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_is_replaced </td>
          <td>(</td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>func</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<dl class="section return"><dt>Returns:</dt><dd>whether <code>func</code> is currently replaced via <a class="el" href="group__drwrap.html#ga488a6566cd760a3919bdd2f49a6d672f">drwrap_replace()</a> </dd></dl>

</div>
</div>
<a class="anchor" id="ga87ab96ab2d3c5cc33480693266b33249"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_is_replaced_native </td>
          <td>(</td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>func</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<dl class="section return"><dt>Returns:</dt><dd>whether <code>func</code> is currently replaced via <a class="el" href="group__drwrap.html#ga0ae2e383b0005a46848c7d0497be563a">drwrap_replace_native()</a> </dd></dl>

</div>
</div>
<a class="anchor" id="ga01e56e9bac8f584fe25e806a24769d50"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_is_wrapped </td>
          <td>(</td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>func</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void(*)(void *wrapcxt, OUT void **user_data)&#160;</td>
          <td class="paramname"><em>pre_func_cb</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void(*)(void *wrapcxt, void *user_data)&#160;</td>
          <td class="paramname"><em>post_func_cb</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<dl class="section return"><dt>Returns:</dt><dd>whether <code>func</code> is currently wrapped with <code>pre_func_cb</code> and <code>post_func_cb</code>. </dd></dl>

</div>
</div>
<a class="anchor" id="ga61b97c33203c704dd8ff1b9d31b3d2a9"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_mark_as_post_call </td>
          <td>(</td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>pc</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Records the address <code>pc</code> as a post-call address for instrumentation for post-call function wrapping purposes.</p>
<dl class="section note"><dt>Note:</dt><dd>Only call this when the code leading up to <code>pc</code> is legitimate, as that code will be stored for consistency purposes and the post-call entry will be invalidated if it changes. This means that when using this routine for the performance purposes described in the <a class="el" href="group__drwrap.html#ga0f84bd239ed2f9f3550d66b75fb9b392">drwrap_register_post_call_notify()</a> documentation, the tool should wait for a newly loaded module to be relocated before calling this routine. A good approach is to wait for the first execution of code from the new module.</dd></dl>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="ga0f84bd239ed2f9f3550d66b75fb9b392"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_register_post_call_notify </td>
          <td>(</td>
          <td class="paramtype">void(*)(app_pc pc)&#160;</td>
          <td class="paramname"><em>cb</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Registers a callback <code>cb</code> to be called every time a new post-call address is encountered. The intended use is for tools that want faster start-up time by avoiding flushes for inserting wrap instrumentation at post-call sites. A tool can use this callback to record all of the post-call addresses to disk, and use <a class="el" href="group__drwrap.html#ga61b97c33203c704dd8ff1b9d31b3d2a9">drwrap_mark_as_post_call()</a> during module load of the next execution. It is up to the tool to verify that the module has not changed since its addresses were recorded.</p>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="ga488a6566cd760a3919bdd2f49a6d672f"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_replace </td>
          <td>(</td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>original</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>replacement</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>override</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Replaces the application function that starts at the address <code>original</code> with the code at the address <code>replacement</code>.</p>
<p>Only one replacement is supported per target address. If a replacement already exists for <code>original</code>, this function fails unless <code>override</code> is true, in which case it replaces the prior replacement. To remove a replacement, pass NULL for <code>replacement</code> and <b>true</b> for <code>override</code>. When removing or replacing a prior replacement, existing replaced code in the code cache will be flushed lazily: i.e., there may be some execution in other threads after this call is made.</p>
<p>Only the first target replacement address in a basic block will be honored. All code after that address is removed.</p>
<p>When replacing a function, it is up to the user to ensure that the replacement mirrors the calling convention and other semantics of the original function. The replacement code will be executed as application code, NOT as client code.</p>
<dl class="section note"><dt>Note:</dt><dd>The priority of the app2app pass used here is DRMGR_PRIORITY_APP2APP_DRWRAP and its name is DRMGR_PRIORITY_NAME_DRWRAP.</dd></dl>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="ga0ae2e383b0005a46848c7d0497be563a"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_replace_native </td>
          <td>(</td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>original</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>replacement</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>at_entry</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">uint&#160;</td>
          <td class="paramname"><em>stack_adjust</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>user_data</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">bool&#160;</td>
          <td class="paramname"><em>override</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<dl class="section warning"><dt>Warning:</dt><dd>This interface is in flux and is subject to change in the next release. Consider it experimental in this release.</dd></dl>
<p>Replaces the application function that starts at the address <code>original</code> with the natively-executed (i.e., as the client) code at the address <code>replacement</code>. The replacement should either be the function entry point or a call site for the function, indicated by the <code>at_entry</code> parameter. For a call site, only that particular call will be replaced, rather than every call to <code>replacement</code>.</p>
<p>The replacement function must call <a class="el" href="group__drwrap.html#gadadab62f67c3e8198762776012a66fce">drwrap_replace_native_fini()</a> prior to returning. If it fails to do so, control will be lost and subsequent application code will not be under DynamoRIO control. The fini routine sets up a continuation function that is used rather than a direct return. This continuation strategy enables the replacement function to use application locks (if they are marked with <a class="el" href="dr__tools_8h.html#a28d121869aba7466a553effe8356bf5e">dr_mark_safe_to_suspend()</a>) safely, as there is no code cache return point.</p>
<p>The replacement function should use the same calling convention as the original with respect to argument access. In order to match the calling convention return for conventions in which the callee cleans up arguments on the stack, use the <code>stack_adjust</code> parameter to request a return that adjusts the stack. This return will be executed as a regular basic block and thus a stack-tracking client will not observe any missing stack adjustments. The <code>stack_adjust</code> parameter must be a multiple of sizeof(void*).</p>
<p>If <code>user_data</code> != NULL, it is stored in a scratch slot for access by <code>replacement</code> by calling <a class="el" href="dr__ir__utils_8h.html#abb63ecfaa5256688bab9a2921fc19227">dr_read_saved_reg()</a> and passing DRWRAP_REPLACE_NATIVE_DATA_SLOT.</p>
<p>Only one replacement is supported per target address. If a replacement already exists for <code>original</code>, this function fails unless <code>override</code> is true, in which case it replaces the prior replacement. To remove a replacement, pass NULL for <code>replacement</code> and <b>true</b> for <code>override</code>. When removing or replacing a prior replacement, existing replaced code in the code cache will be flushed lazily: i.e., there may be some execution in other threads after this call is made.</p>
<p>Non-native replacements take precedence over native. I.e., if a <a class="el" href="group__drwrap.html#ga488a6566cd760a3919bdd2f49a6d672f">drwrap_replace()</a> replacement exists for <code>original</code>, then a native replacement request for <code>original</code> will never take effect.</p>
<p>Only the first target replacement address in a basic block will be honored. All code after that address is removed.</p>
<p>When replacing a function, it is up to the user to ensure that the replacement mirrors the calling convention and other semantics of the original function.</p>
<p>The replacement code will be executed as client code, NOT as application code. However, it will use the application stack and other machine state. Usually it is good practice to call <a class="el" href="dr__tools_8h.html#aa2944aa54d591a236f5334a35bfb41bf">dr_switch_to_app_state()</a> inside the replacement code, and then <a class="el" href="dr__tools_8h.html#a97ba972c50a47e7121c98652b461ae8e">dr_switch_to_dr_state()</a> before returning, in particular on Windows. To additionally use a clean DR stack, consider using <a class="el" href="dr__ir__utils_8h.html#a4473973127fba8a57f1a4ba409c6938a">dr_call_on_clean_stack()</a> from the initial replacement layer (which allows the outer layer to handle stdcall, which dr_call_on_clean_stack does not support).</p>
<p>The replacement code is not allowed to invoke <a class="el" href="dr__tools_8h.html#abe87d17869a51a66d59eecf459d71cc0">dr_flush_region()</a> or <a class="el" href="dr__tools_8h.html#a7600cc31d68dc0e30ab91261d08836ed">dr_delete_fragment()</a> as it has no <a class="el" href="dr__defines_8h.html#a5d50a4225e834d67f66438669608e435">dr_mcontext_t</a> with which to invoke <a class="el" href="dr__ir__utils_8h.html#a9f612cf9d0ca2025b23d30b6f5bb0231">dr_redirect_execution()</a>: it must return to the call-out point in the code cache. If the replacement code does not return to its return address, DR will lose control of the application and not continue executing it properly.</p>
<dl class="params"><dt>Parameters:</dt><dd>
  <table class="params">
    <tr><td class="paramdir">[in]</td><td class="paramname">original</td><td>The address of either the application function entry point (in which case <code>at_entry</code> must be true) or of a call site (the actual call or tailcall/inter-library jump) (in which case <code>at_entry</code> must be false). </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">replacement</td><td>The function entry to use instead. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">at_entry</td><td>Indicates whether <code>original</code> is the function entry point or a call site. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">stack_adjust</td><td>The stack adjustment performed at return for the calling convention used by <code>original</code>. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">user_data</td><td>Data made available when <code>replacement</code> is executed. </td></tr>
    <tr><td class="paramdir">[in]</td><td class="paramname">override</td><td>Whether to replace any existing replacement for <code>original</code>.</td></tr>
  </table>
  </dd>
</dl>
<dl class="section note"><dt>Note:</dt><dd>The mechanism used for a native replacement results in a <code>ret</code> instruction appearing in the code stream with an application address that is different from an execution without a native replacement. The return address will be identical, however, assuming <code>original</code> does not replace its own return address.</dd>
<dd>
The application stack address at which its return address is stored is available by calling <a class="el" href="dr__ir__utils_8h.html#abb63ecfaa5256688bab9a2921fc19227">dr_read_saved_reg()</a> and passing DRWRAP_REPLACE_NATIVE_SP_SLOT.</dd>
<dd>
The priority of the app2app pass used here is DRMGR_PRIORITY_APP2APP_DRWRAP and its name is DRMGR_PRIORITY_NAME_DRWRAP.</dd>
<dd>
Far calls are not supported.</dd></dl>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="gadadab62f67c3e8198762776012a66fce"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT void drwrap_replace_native_fini </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>drcontext</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>The replacement function passed to <a class="el" href="group__drwrap.html#ga0ae2e383b0005a46848c7d0497be563a">drwrap_replace_native()</a> must call this function prior to returning. If this function is not called, DynamoRIO will lose control of the application. </p>

</div>
</div>
<a class="anchor" id="ga17937b1d8ff7e391814e4e6e6df5c807"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_set_arg </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">int&#160;</td>
          <td class="paramname"><em>arg</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>val</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Sets the the <code>arg-th</code> argument (0-based) to the wrapped function represented by <code>wrapcxt</code> to <code>val</code>. Assumes the regular C calling convention (i.e., no fastcall). May only be called from a <code>drwrap_wrap</code> pre-function callback. To access argument values in a post-function callback, store them in the <code>user_data</code> parameter passed between the pre and post functions.</p>
<p>This routine may write to application memory directly, so the caller should wrap in DR_TRY_EXCEPT if crashes must be avoided. </p>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="gae2cc2affaf879182ba4d92299704c65f"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_set_global_flags </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="group__drwrap.html#gab82c71baab4fe0c5f9962383818b9c92">drwrap_global_flags_t</a>&#160;</td>
          <td class="paramname"><em>flags</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Sets flags that affect the global behavior of the drwrap module. This can be called at any time and it will affect future behavior. </p>
<dl class="section return"><dt>Returns:</dt><dd>whether the flags were changed. </dd></dl>

</div>
</div>
<a class="anchor" id="gae4a50709cf98fca89860c09543176fa6"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_set_mcontext </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Propagates any changes made to the dr_mcontext_t pointed by <a class="el" href="group__drwrap.html#ga9a33b1049986dd8975e94827f5c0e759">drwrap_get_mcontext()</a> back to the application.</p>
<dl class="section note"><dt>Note:</dt><dd>if the <a class="el" href="group__drwrap.html#ggab82c71baab4fe0c5f9962383818b9c92add150e3e7ba4ee203a045b936f872b4b">DRWRAP_FAST_CLEANCALLS</a> flag is set, caller-saved register values in the fields controlled by <a class="el" href="dr__defines_8h.html#af0434595b47158e7512c2bf5f0e43ae4af3780bef723b8bf1a34eb75125f7f122">DR_MC_MULTIMEDIA</a> will not contain valid values, but this should be fine because their values were scratch according to the ABI at the wrap point.. </dd></dl>

</div>
</div>
<a class="anchor" id="gafd31e6725143df904e766dbfa508db05"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_set_retval </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>val</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Sets the return value of the wrapped function represented by <code>wrapcxt</code> to <code>val</code>. Assumes a pointer-sized return value. May only be called from a <code>drwrap_wrap</code> post-function callback. </p>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="gae539b1092ba0c1a3e86172964a671805"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_skip_call </td>
          <td>(</td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>wrapcxt</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>retval</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">size_t&#160;</td>
          <td class="paramname"><em>stdcall_args_size</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>May only be called from a <code>drwrap_wrap</code> pre-function callback. Skips execution of the original function and returns to the function's caller with a return value of <code>retval</code>. The post-function callback will not be invoked; nor will any pre-function callbacks (if multiple were registered) that have not yet been called. If the original function uses the <code>stdcall</code> calling convention, the total size of its arguments must be supplied. The return value is set regardless of whether the original function officially returns a value or not. Further state changes may be made with <a class="el" href="group__drwrap.html#ga9a33b1049986dd8975e94827f5c0e759">drwrap_get_mcontext()</a> and <a class="el" href="group__drwrap.html#gae4a50709cf98fca89860c09543176fa6">drwrap_set_mcontext()</a> prior to calling this function.</p>
<dl class="section note"><dt>Note:</dt><dd>It is up to the client to ensure that the application behaves as desired when the original function is skipped.</dd></dl>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="ga1b4b6da75fceb5977ff1f82bf3ffd8c9"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_unregister_post_call_notify </td>
          <td>(</td>
          <td class="paramtype">void(*)(app_pc pc)&#160;</td>
          <td class="paramname"><em>cb</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Unregisters a callback registered with <a class="el" href="group__drwrap.html#ga0f84bd239ed2f9f3550d66b75fb9b392">drwrap_register_post_call_notify()</a>. </p>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="ga27894370f3da794ff3f31cb8d7ec079b"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_unwrap </td>
          <td>(</td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>func</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void(*)(void *wrapcxt, OUT void **user_data)&#160;</td>
          <td class="paramname"><em>pre_func_cb</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void(*)(void *wrapcxt, void *user_data)&#160;</td>
          <td class="paramname"><em>post_func_cb</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Removes a previously-requested wrap for the function <code>func</code> and the callback pair <code>pre_func_cb</code> and <code>post_func_cb</code>. This must be the same pair that was passed to <code>dr_wrap</code>.</p>
<p>This routine can be called from <code>pre_func_cb</code> or <code>post_func_cb</code>.</p>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="ga4c004987daae07af15f2146c2d7d4b09"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_wrap </td>
          <td>(</td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>func</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void(*)(void *wrapcxt, OUT void **user_data)&#160;</td>
          <td class="paramname"><em>pre_func_cb</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void(*)(void *wrapcxt, void *user_data)&#160;</td>
          <td class="paramname"><em>post_func_cb</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Wraps the application function that starts at the address <code>original</code> by calling <code>pre_func_cb</code> prior to every invocation of <code>original</code> and calling <code>post_func_cb</code> after every invocation of <code>original</code>. One of the callbacks can be NULL, but not both.</p>
<p>Wrap requests should normally be made up front during process initialization or module load (see <a class="el" href="dr__events_8h.html#aca6b098123ef80cae05ce767a7dd9d98">dr_register_module_load_event()</a>). If a wrap request is made after the target code may have already been executed by the application, the caller should flush the target code from the cache using the desired flush method after issuing the wrap request.</p>
<p>Multiple wrap requests are allowed for one <code>original</code> function (unless <a class="el" href="group__drwrap.html#ggab82c71baab4fe0c5f9962383818b9c92aeb299993e17993cb86912f93391f6b86">DRWRAP_NO_FRILLS</a> is set). Their callbacks are called sequentially in the reverse order of registration.</p>
<p>The <code>pre_func_cb</code> can examine (<a class="el" href="group__drwrap.html#ga3d0864daf1ec37a91640a739f8928b83">drwrap_get_arg()</a>) and set (<a class="el" href="group__drwrap.html#ga17937b1d8ff7e391814e4e6e6df5c807">drwrap_set_arg()</a>) the arguments to <code>original</code> and can skip the call to <code>original</code> (<a class="el" href="group__drwrap.html#gae539b1092ba0c1a3e86172964a671805">drwrap_skip_call()</a>). The <code>post_func_cb</code> can examine (<a class="el" href="group__drwrap.html#gae993f55e025cf80ae67ed398b35a1b61">drwrap_get_retval()</a>) and set (<a class="el" href="group__drwrap.html#gafd31e6725143df904e766dbfa508db05">drwrap_set_retval()</a>) <code>original's</code> return value. The opaque pointer <code>wrapcxt</code> passed to each callback should be passed to these routines.</p>
<p>When an abnormal stack unwind, such as longjmp or a Windows exception, occurs, drwrap does its best to detect it. All post-calls that would be missed will still be invoked, but with <code>wrapcxt</code> set to NULL. Since there is no post-call environment, it does not make sense to query the return value or arguments. The call is invoked to allow for cleanup of state allocated in <code>pre_func_cb</code>. However, detection of a stack unwind is not guaranteed. When wrapping a series of functions that do not themselves contain exception handlers, pass the DRWRAP_UNWIND_ON_EXCEPTION flag to <a class="el" href="group__drwrap.html#gaff6f66f7ec021cea150eb753f5db2b75">drwrap_wrap_ex()</a> to ensure that all post-call callbacks will be called on an exception.</p>
<dl class="section note"><dt>Note:</dt><dd>The priority of the app2app pass used here is DRMGR_PRIORITY_INSERT_DRWRAP and its name is DRMGR_PRIORITY_NAME_DRWRAP.</dd></dl>
<dl class="section return"><dt>Returns:</dt><dd>whether successful. </dd></dl>

</div>
</div>
<a class="anchor" id="gaff6f66f7ec021cea150eb753f5db2b75"></a>
<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">DR_EXPORT bool drwrap_wrap_ex </td>
          <td>(</td>
          <td class="paramtype">app_pc&#160;</td>
          <td class="paramname"><em>func</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void(*)(void *wrapcxt, INOUT void **user_data)&#160;</td>
          <td class="paramname"><em>pre_func_cb</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void(*)(void *wrapcxt, void *user_data)&#160;</td>
          <td class="paramname"><em>post_func_cb</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">void *&#160;</td>
          <td class="paramname"><em>user_data</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="group__drwrap.html#ga16cc419209fcb0024d010599bb82aa76">drwrap_wrap_flags_t</a>&#160;</td>
          <td class="paramname"><em>flags</em>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">
<p>Identical to <a class="el" href="group__drwrap.html#ga4c004987daae07af15f2146c2d7d4b09">drwrap_wrap()</a> except for two additional parameters: <code>user_data</code>, which is passed as the initial value of *user_data to <code>pre_func_cb</code>, and <code>flags</code>. </p>

</div>
</div>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer" style="float:none;text-align:center"><img border=0 src="favicon.png"> &nbsp;  DynamoRIO API version 5.0.0 --- Wed Sep 10 2014 21:36:44 &nbsp; <img border=0 src="favicon.png">
</small></address>
<!--END !GENERATE_TREEVIEW-->
</body>
</html>
